package org.example.exampreparationtreasure.service;

import org.example.exampreparationtreasure.model.entity.Categories;
import org.example.exampreparationtreasure.model.entity.Question;
import org.example.exampreparationtreasure.model.vo.CategoryTreeNode;

import java.util.List;

/**
 * 分类服务接口。
 * <p>
 * 提供题目分类的树形结构管理、层级查询与题目检索能力，满足前端分类树展示、
 * 扁平后代查询、按分类聚合题目等需求。
 * </p>
 *
 * <p>
 * 约定与假设：
 * <ul>
 *   <li>题目仅挂载在叶子分类（没有子分类的节点）。</li>
 *   <li>父分类 ID 顶层使用 0 或 null 表示。</li>
 *   <li>除特别说明外，方法返回的列表默认按业务字段升序（如 sortWeight、ID）。</li>
 * </ul>
 * </p>
 */
public interface CategoryService {
    /**
     * 获取完整的分类树结构（含多级 children）。
     *
     * @return 根节点列表；每个根节点的 {@code children} 递归包含其所有子节点
     */
    List<CategoryTreeNode> getCategoryTree();

    /**
     * 获取指定父分类的直接子分类（仅一层）。
     *
     * @param parentCategoryId 父分类 ID
     * @return 直接子分类列表，按 {@code sortWeight}、{@code categoryId} 升序
     */
    List<Categories> getChildrenByParentId(Long parentCategoryId);

    /**
     * 获取指定分类下的题目（不递归，不包含子分类）。
     *
     * @param categoryId 分类 ID
     * @return 题目列表，按 {@code questionId} 升序
     */
    List<Question> getQuestionsByCategoryId(Long categoryId);

    /**
     * 递归获取指定父分类的所有后代分类（扁平列表）。
     *
     * @param parentCategoryId 父分类 ID
     * @return 所有后代分类的扁平列表，按 {@code sortWeight}、{@code categoryId} 升序；若无子孙分类返回空列表
     */
    List<Categories> getAllDescendantsByParentId(Long parentCategoryId);

    /**
     * 获取指定父分类下所有后代分类中的题目（聚合）。
     * <p>
     * 假设题目仅出现在叶子分类；方法会聚合所有后代分类的题目并返回扁平列表。
     * </p>
     *
     * @param parentCategoryId 父分类 ID
     * @return 题目扁平列表，按 {@code questionId} 升序；若无后代/题目返回空列表
     */
    List<Question> getAllQuestionsByParentCategoryId(Long parentCategoryId);
}


